This document describes AMan, a documentation browser for the Amiga. Copyright © 1994,95 by Tobias Ferber, <ferber@rpk.mach.uni-karlsruhe.de>.

GNU GENERAL PUBLIC LICENSE
**************************

gpl.texinfo

Introduction
************

AMan is a documentation browser for the Amiga.  The idea is very simple and the implementation is simple as well:  Similar to the Unix man command it locates documentation files on your disk and spawns an external viewer.  AMan uses the FDB tool by Klaus Melchior to locate the files and opens a minimal MUI window to allow a selection.  See FDB, and MUI, for details. Of course these tools are not included in this archive.

Actually, AMan is only a quick hack.  I initially wrote this tool for my private use only and I wrote it simply because I didn't want to use MrMan anymore. Nevertheless, AMan's concept is quite close to that of MrMan, however it makes heavily use of the said tools which are installed on my system anyway.  And why should I invent the wheel over and over again?  Even Stuntzi's MagicFileRequester (MFR) makes use of FDB!

Installing AMan
***************

Requirements
============

AMan makes heavily use of some tools which therefore must be installed on your system. Of course these tools are not included in this archive.

  * Kickstart/Workbench V37 or better (including More and AmigaGuide or MultiView respectively).

  * The MagicUserInterface MUI. See MUI, for details. I tested AMan with muimaster.library version 10.0.

  * The FindDB clone FDB. See FDB, for more information. The archive util/cli/FDB1_3.lha can be obtained (e.g. via ftp) from the Aminet. Please make sure that the FDB executable is in your path!

Besides that, a pager like Most or MuchMore is recommend but not required.

Installation
============

Installing AMan is quite simple.  You only have to copy the file aman.000 (or aman.030 if you have an MC-68030 Amiga) somewhere into your path (e.g. to C:) and rename it to aman.

     Copy aman.030 TO C:aman

You might as well want to install the ldb2db tool.  See Hints, for a description. Simply copy it somewhere into your path as well.

Since AMan needs FDB, you have to install FDB if you don't already have it. You should now make a database via UDB.  Note that by default, AMan will only find files which are listed in FindDB:aman.codes. For example you might want to try the following:

     UDB DB=aman help:

This will create the database FindDB:aman.codes which contains all files in help:. If you are using AMan regularly then you might want to create a file FindDB:aman.config which contains all the pathnames that should be scanned if you type UDB DB=aman. For example,

     Echo >FindDB:aman.config "help: docs: autodocs: gnu:man/"

Before running AMan for the first time, you should make sure that MUI is installed on your system. See MUI, for details.

AMan is now ready for a first take-off.  However, AMan will assume you want to use MultiView to view all types of documents.  If you prefer some other pagers then you have to create a file ENV:aman.config.  This file will be parsed by AMan via ReadArgs() in order to find out which viewer to use for the selected filename. The following example is included in this archive:

     ; Template: PATTERN/A,COMMAND/A

     "#?.(doc|readme|txt)"  "Most *"%s*""
     "#?.dvi"               "ShowDVI *"%s*""
     "#?.guide"             "AmigaGuide *"%s*""
     "#?"                   "MultiView *"%s*""

Empty lines and lines beginning with a semicolon ; are ignored. If no pattern matches or if ENV:mrman.config does not exist, then AMan uses the following default:

     PATTERN "#?"  COMMAND "Run <NIL: >NIL: MultiView *"%s*""

As you can see it is also possible to run viewers asynchronously.  For those among you who like it even more complex:  I use the following command for the pattern "#?/man[1-9]/#?.[1-9]" in my aman.config:

     "NewWSH CONSOLE NIL: COMMAND *"groff -Tascii -man ***"%s***" | More*""

Example: Okay, lets try out AMan now.  First we will create an FDB database for AMan from the gnu:man directory:

     UDB db=aman gnu:man/

Now let's see whether AMan knows something about gcc.

     aman gcc

AMan should now open a MUI window with a listview containing some alphabetically sorted entries like that:

     gnu:man/man1/gcc.0
     gnu:man/cat1/hunk2gcc.0
     gnu:man/cat1/gcc.0
     gnu:man/man1/gcc.1

Simply select one of those with your cursor keys and press Return. Your viewer should spawn and show the selected document.  Press ESC to quit AMan.

Invoking AMan
*************

Running AMan From A Shell
=========================

When invoked from within a shell, AMan uses ReadArgs() with the following template in order to parse command-line arguments:

     DB=DataBase/K,H=Hide/K,E=Exact/S,P=Pattern/A/M

The DB=DataBase parameter can be used to force AMan to use a different database than FindDB:aman.codes.  For example,

     aman db=find .texi

will use the default database FindDB:find.codes to locate Texinfo files. Especially when using other databases there might also appear non-doc files in AMan's listview which you might want to Hide... For example, to avoid the listing of icons you can invoke AMan as follows:

     aman hide #?.info .dvi

This will show all the .dvi files listed in FindDB:aman.codes but not their icons.

Note: The patterns given to AMan are directly passed to FDB. Especially the E=Exact/S switch is an FDB switch which allows real AmigaDOS patterns instead of only a sub-strings. Please consult your FDB documentation for details.  (E.g. via aman fdb)

Note also: AMan internally makes use of the FDB switch F=Files/S. Nevertheless, FDB returns directories together with files every now and then. It's a good idea to invoke AMan with the option HIDE #?/ as a workaround to avoid the listing of directories in AMan's listview.

Running AMan From The Workbench
===============================

Especially when starting AMan from the Workbench the Pattern string gadget is needed.  It is active automatically when run from the Workbench, however it can be easily toggled by pressing the TAB key when inactive.

After pressing Return in the string gadget, AMan will parse it's contents via ReadArgs() using the same template as when invoked from the shell. This guarantees full functionality without too much effort. ;-)

Hints & Tips
************

AMan always strives to allow intuitive usage.  Nevertheless, some of the following hints might help you to make full profit of what AMan offers.

Extracting aman.codes From Other Databases
==========================================

Good applications, especially if they have their own drawer, want their doumentation located inside this drawer as well.  This makes sense since uninstalling such an application by simply deleting it's drawer will leave no trails.  However, this way the documentation files are spread all over your disk(s) in their application drawers which makes maintaining the FDB configuration aman.config quite hard.  This is why I wrote ldb2db, a quick hack which converts a list of files into a FDB compatible database. Let me explain how to use ldb2db:

I regularly perform an UDB of my three main partitions: System:, Work: and Devel: via CyberCron.  My CronTab entry looks like this:

     15  1    * * *    UDB System: Work: Devel:  :PRI -5

Now of course all the documentation files have already been collected into this database! The LDB tool, which is part of the FDB distribution, can be used to list the files in a database to stdout and here it comes to ldb2db:

     LDB find | pgrep -x -i #?.(doc|guide) | ldb2db >FindDB:aman.codes

This extracts all .doc or .guide files listed in FindDB:find.codes to FindDB:aman.codes. Of course you can also specify a larger pattern for pgrep such as

     pgrep -x -i #?.(guide|doc|man|txt|readme|dvi|ps|texi|texinfo)

Note: pgrep is FreeWare and was written by Angela Schmidt, angela@rz.uni-karlsruhe.de. It is available with her pattern.library distribution.

FDB -- A FindDB/UpdateDB Clone
******************************

The FDB and UDB tools base on FindDB and UpdateDB by Larry Phillips and Martin Steppler.  UDB collects filenames from a couple of path names into a database file and FDB locates patterns in these databases.  AMan uses FDB in order to retrieve the documentation files.

FDB is © Copyright 1993-94 kMel, Klaus Melchior,
Schulstraße 17, D-52156 Monschau, Germany.  Phone: +49 (0)2472 4710

ADSP: kmel@eifel.adsp.sub.org DE:   kmel@eifel.fido.de FIDO: 2:242/7.2@fidonet, 2:2452/107.2@fidonet

MUI -- MagicUserInterface
*************************

AMan uses

MUI - MagicUserInterface
© Copyright 1993/94 by Stefan Stuntz

MUI is a system to generate and maintain graphical user interfaces. With the aid of a  preferences program, the user of an application has the ability to customize the outfit according to his personal taste.

MUI is distributed as shareware.  To obtain a complete package containing lots of examples and more information about registration please look for a  file  called muiXXusr.lha  (XX means the latest version number) on your local bulletin boards or on public domain disks.

If you want to register directly, feel free to send DM 30.--  or  US$ 20.-- to

Stefan Stuntz
Eduard-Spranger-Straße 7
80935 München
GERMANY